---
title: Setup
---

import { Card, Tabs, TabItem, CardGrid, Icon } from '@astrojs/starlight/components'
import Seo from '../../../components/Seo.astro'
import Badge from '../../../components/Badge.astro'

<Seo
    seo={{
        title: 'Setup',
        description: 'How to Setup react-native-unistyles?'
    }}
>
    ### 1. Install package

    ```cmd
    yarn add react-native-unistyles
    ```

    ### 2. Finish installation

    <Tabs>
    <TabItem label="Expo">
      <Card title="Dev client only">
         Unistyles includes custom native code, which means **it does not support Expo Go**.
      </Card>

      To finish the setup use <a href="https://docs.expo.dev/develop/development-builds/introduction/" target="_blank">expo dev client</a> and run `prebuild` command:

      ```cmd
      yarn expo prebuild --clean
      ```
    </TabItem>
    <TabItem label="Bare">
      Library supports autolinking, to finish the setup run `pod install`:

      ```cmd
      cd ios && pod install
      ```
    </TabItem>
    <TabItem label="Web">

      Unistyles offers first-class support for React Native Web. To run the project, we recommend following the guidelines provided by <a href="https://docs.expo.dev/workflow/web/" target="_blank">Expo</a>:

      ```cmd
      yarn expo add react-dom react-native-web @expo/webpack-config
      ```

    </TabItem>
    <TabItem label="NextJS">
      Library supports also Server Side Rendering. We recommend to setup to project with <a href="https://solito.dev" target="_blank">Solito</a>:

      ```cmd
      npx create-solito-app@latest my-solito-app
      ```
    </TabItem>

    <TabItem label="macOS">
      You can also style your `macOS` apps using `react-native-unistyles`.
      Please follow the instructions provided by <a href="https://microsoft.github.io/react-native-windows/docs/rnm-getting-started" target="_blank">react-native-macos</a> and then:

      Open `macos/Podfile` and add the following line:
      ```txt title="Podfile" /pod.*/
      target 'macos-macOS' do
        # add this line somewhere within the target scope
        pod 'react-native-unistyles', :path => '../node_modules/react-native-unistyles'
      end
      ```

      Then run `pod install`:

      ```cmd title="macos"
      pod install
      ```

:::caution
Remember to add this line to the `macos` folder, not the `ios` folder!
:::
    </TabItem>
    <TabItem label="Windows">
    <Badge label="2.3.0" />

      Windows is also supported with <a href="https://microsoft.github.io/react-native-windows/docs/getting-started" target="_blank">react-native-windows</a> package.
      Simply install the package and it will be auto-linked.

    </TabItem>
    <TabItem label="tvOS">
      Please follow official installation guide for <a href="https://github.com/react-native-tvos/react-native-tvos" target="_blank">react-native-tvOS</a>:

      Then run `pod install`:

      ```cmd title="tvos"
      pod install
      ```
    </TabItem>
    <TabItem label="visionOS">
      Please follow the instructions provided by <a href="https://callstack.github.io/react-native-visionos-docs" target="_blank">react-native-visionos</a>:

      Then run `pod install`:

      ```cmd title="visionos"
      pod install
      ```
    </TabItem>
   </Tabs>

   ### 3. Configure Unistyles with `UnistylesRegistry`


  Every step mentioned here is optional. If you don't want to use theming, breakpoints, or any other setting, you don't need to even call `UnistylesRegistry`.
  You can jump directly into working on your components.

     <Card>
          Remember that `UnistylesRegistry` should be called only once. If you want to interact with Unistyles use `UnistylesRuntime` as described [here](/reference/unistyles-runtime).
     </Card>

    ### 3.1 Define your breakpoints

    You can name your breakpoints however you like. The only restriction is that the first breakpoint must start with `0`:

      ```ts {3}
    // breakpoints.ts
    export const breakpoints = {
        xs: 0,
        sm: 576,
        md: 768,
        lg: 992,
        xl: 1200,
        superLarge: 2000,
        tvLike: 4000
    } as const
    ```

    ### 3.2 Define your theme(s)


You can define as many themes as you want. Each theme just needs to have a unique name and the same type.
The library has no restrictions on the shape of the theme. You can use nested objects, functions, spread operators, and so on.

   ```ts
    // themes.ts
    export const lightTheme = {
      colors: {
        typography: '#000000',
        background: '#ffffff'
      },
      margins: {
        sm: 2,
        md: 4,
        lg: 8,
        xl: 12
      }
    } as const

    export const darkTheme = {
      colors: {
        typography: '#ffffff',
        background: '#000000'
      },
      margins: {
        sm: 2,
        md: 4,
        lg: 8,
        xl: 12
      }
    } as const

    // define other themes
    ```

    ### 3.3 Configure TypeScript

    If you're using TypeScript, create types for your breakpoints and/or themes.
    This step is required to achieve perfect Intellisense support across all StyleSheets.

    ```ts
    //unistyles.ts

    // if you defined breakpoints
    type AppBreakpoints = typeof breakpoints

    // if you defined themes
    type AppThemes = {
      light: typeof lightTheme,
      dark: typeof darkTheme
    }

    // override library types
    declare module 'react-native-unistyles' {
      export interface UnistylesBreakpoints extends AppBreakpoints {}
      export interface UnistylesThemes extends AppThemes {}
    }
    ```

:::tip[Did you encounter errors like these?]

`"An interface declaring no members is equivalent to its supertype."`

Don't worry! This issue arises due to the eslint preset. To fix it, disable the following [rule](https://typescript-eslint.io/rules/no-empty-interface/).

`"TS2664: Invalid module name in augmentation, module 'react-native-unistyles' cannot be found."`

To resolve this, simply follow the steps described below. You need to import something from `react-native-unistyles`.
:::

    ### 3.4 Call `UnistylesRegistry`

    The final step is to call `UnistylesRegistry` to pass your themes, breakpoints and optional config.

    ```ts
    //unistyles.ts
    import { UnistylesRegistry } from 'react-native-unistyles'

    UnistylesRegistry
      .addBreakpoints(breakpoints)
      .addThemes({
        light: lightTheme,
        dark: darkTheme,
        // register other themes with unique names
      })
      .addConfig({
        // you can pass here optional config described below
        adaptiveThemes: true
      })
    ```

:::caution
  In order to run the code don't forget to import the `unistyles.ts` file somewhere in your app eg. in the `App.tsx` file.

  ```diff lang="ts"
  import '../unistyles'
  ```
:::

    #### Optional config

    `UnistylesRegistry` has a method called `addConfig` that let's you use some cool additional features.
    List of all available settings can be found [here](/reference/unistyles-registry).

    ### 3.5 Full example

    ```ts
    //unistyles.ts
    import { UnistylesRegistry } from 'react-native-unistyles'
    import { breakpoints } from './breakpoints'
    import { lightTheme, darkTheme } from './themes'

    type AppBreakpoints = typeof breakpoints
    type AppThemes = {
      light: typeof lightTheme,
      dark: typeof darkTheme
    }

    declare module 'react-native-unistyles' {
      export interface UnistylesBreakpoints extends AppBreakpoints {}
      export interface UnistylesThemes extends AppThemes {}
    }

    UnistylesRegistry
      .addBreakpoints(breakpoints)
      .addThemes({
        light: lightTheme,
        dark: darkTheme,
      })
      .addConfig({
        adaptiveThemes: true
      })
    ```
</Seo>
